From 1d196f7313688f45fdb018330113b0d2e84ceef6 Mon Sep 17 00:00:00 2001 From: parkrrrr Date: Wed, 24 May 2006 23:44:44 +0000 Subject: [PATCH] Merged README.* into docs Fixed problem with xcsv derivatives that contained sections in the description. --- xmldoc/formats/igc.xml | 138 ++++++++++++++- xmldoc/formats/magnav.xml | 48 +++++- xmldoc/formats/mapconverter.xml | 66 +++++++- xmldoc/formats/options/igc-timeadj.xml | 15 ++ xmldoc/formats/psp.xml | 224 +++++++++++++++++++++++-- xmldoc/formats/xmapwpt.xml | 82 ++++++++- xmldoc/makedoc | 2 +- 7 files changed, 537 insertions(+), 38 deletions(-) diff --git a/xmldoc/formats/igc.xml b/xmldoc/formats/igc.xml index 0a8c75d5d..0c1485b6e 100644 --- a/xmldoc/formats/igc.xml +++ b/xmldoc/formats/igc.xml @@ -1,8 +1,134 @@ - - - - FAI/IGC Data File -- Used by the international gliding + +FAI/IGC Data File -- Used by the international gliding community to record gliding flights. IGC files can be converted to and from tracks representing recorded flights, and routes representing -task declarations in other formats. - +task declarations in other formats. + + +
+IGC Data Format Notes + +Refer to Appendix 1 of +http://www.fai.org:81/gliding/gnss/tech_spec_gnss.asp +for the specification of the IGC data format. + + +A sample list of software applications that use data in IGC format can be +found at +http://www.fai.org:81/gliding/gnss/gnss_analysis_software.pdf + + +GPSBabel can be used to translate data in IGC format to and from various other +formats. + + +Routes in other formats are used to represent IGC task declarations. + + +Tracks in other formats are used to represent IGC recorded flights. + +
+ +
+Converting to IGC format + +IGC files generated by GPSBabel will NOT pass security validation tests since +the data they contain cannot be proven to originate from an approved flight +recorder. For most software applications that use IGC files this is not an +issue but for competition scoring, record and badge claims the generated files +will not be accepted as proof of a flight. + + +A track stored in another format (GPX for example) representing a recorded +flight can be converted into an IGC file: + +gpsbabel -i gpx -f mytrk.gpx -o igc -F myflight.igc + +If multiple track segments are provided in the input file, the one with the +most points will be used. + + +A route stored in another format representing a task declaration can be +converted into an IGC file: + +gpsbabel -i gpx -f myrte.gpx -o igc -F mytask.igc + +A route and a track in other formats can be included into a single IGC file: + +gpsbabel -i gpx -f mytrk.gpx -f myrte.gpx -o igc -F myflight.igc + +A similar result can be obtained by downloading the track log and routes +directly from a GPS device connected to a PC. For example to create an IGC +file from data recorded in a Garmin GPS connected to the first serial port of +a PC running Linux: + +gpsbabel -t -r -i garmin -f /dev/ttyS0 -o igc -F myflight.igc + +For Windows operating systems: + +gpsbabel -t -r -i garmin -f com1 -o igc -F myflight.igc + +A waypoint file in another format containing a waypoint whose short name is +"PILOT" can be merged into an IGC file. The description field of the waypoint +will be used for the pilot name in the IGC file header: + +gpsbabel -i gpx -f mytrk.gpx -f myrte.gpx -f mywpt.gpx -o igc -F myflight.igc +gpsbabel -w -t -r -i garmin -f /dev/ttyS0 -o igc -F myflight.igc + +Some formats such as GPX allow routes, tracks and waypoints to exist in the +same file and can be used to fully populate an IGC file: + +gpsbabel -i gpx -f myall.gpx -o igc -F myflight.igc +
+ +
+Converting from IGC format + +Data in an IGC file can be converted into other formats. For example to +generate OziExplorer files containing tracks representing the recorded +flight (myozi.plt) and routes representing declared tasks (myozi.rte): + +gpsbabel -i igc -f myflight.igc -o ozi -F myozi + +Or to GPX format: + +gpsbabel -i igc -f myflight.igc -o gpx -F myflight.gpx + +Header information from the IGC file will be written to the description field +of the track(s). + + +If both pressure altitude and GNSS altitude are recorded in the IGC file, two +tracks will be written to the new track file, representing the two altitude +tracks. The latitude, longitude and timestamps in the tracks will be identical. + +
+ +
+Merging into IGC format + +A route stored in another format can be merged with an existing IGC file that +has no task declaration, to generate a new IGC file with a task declaration: + +gpsbabel -i igc -f myflight.igc -i gpx -f myrte.gpx -o igc -F mynew.igc + +A two dimensional (lat/lon) track recorded during a flight by a GPS receiver +can be merged with a one dimensional (altitude) track recorded during the same +flight by a barograph instrument. The result is a three dimensional IGC file +representing the flight: + +gpsbabel -i gpx -f baro.gpx -i igc -f my2D.igc -o igc -F my3D.igc + +The same can be acheived by downloading directly from a barograph instrument +supported by GPSBabel. For example with a Brauniger IQ Comp GPS variometer: + +gpsbabel -i baroiq -f /dev/ttyS0 -i igc -f my2D.igc -o igc,timeadj=auto -F my3D.igc + +or: + +gpsbabel -i baroiq -f com1 -i igc -f my2D.igc -o igc,timeadj=auto -F my3D.igc + +(Documentation contributed by Chris Jones, Aug 2004) + +
+ diff --git a/xmldoc/formats/magnav.xml b/xmldoc/formats/magnav.xml index ac2a1e9ef..a06a0490e 100644 --- a/xmldoc/formats/magnav.xml +++ b/xmldoc/formats/magnav.xml @@ -1,12 +1,44 @@ - - - - Magellan NAV Companion for Palm/OS is not really designed + +Magellan NAV Companion for Palm/OS is not really designed for this sort of use, but its file format is supported and with a little bit of patience you can both read and write NAV Companion -waypoints. Please read README.magnav for further tips on getting -waypoints in and out of NAV Companion. This conversion is based on +waypoints. This conversion is based on partially incomplete reverse-engineering of the record format, so it may not work with all versions of NAV Companion. It has been tested -with version 2.10 and 3.20. - +with version 2.10 and 3.20. + + +Translating NAV Companion waypoints to another format is as easy +as with any other format. Just find the Companion_Waypoints database +in your palm backup directory and use it as the input file. + + +When translating waypoints back to NAV Companion, though, you need +to jump through some hoops: + + +First, you must merge any waypoints that already exist in the database +in your Palm Backup directory with the ones you are adding; failure to +do so will result in only the new points being available in NAV Companion, +even if you give the new database a different name (it will overwrite +the old database, even in your backup directory. That's a feature of +PalmOS, not of NAV Companion.) + + +To merge the databases, use a command line like the following: + +gpsbabel -i magnav -f Companion_Waypoints.PDB -i geo -f geocaching.loc -o magnav -F merged.pdb + +Second, you must use the installer to install your new PDB file. Don't +make the mistake of copying it over the existing Companion_Waypoints.PDB +file; the one on the handheld will overwrite it rather than merging with +it. + + +Finally, because NAV Companion is not designed to work with desktop +applications, you must tell NAV Companion that its waypoints database +has changed out from under it. One way to do this is to go to the +waypoints screen and attempt to scroll; that will force it to reread +the database and fix the record pointers that it keeps on the heap. + + diff --git a/xmldoc/formats/mapconverter.xml b/xmldoc/formats/mapconverter.xml index fe62f5e9b..1ab390cea 100644 --- a/xmldoc/formats/mapconverter.xml +++ b/xmldoc/formats/mapconverter.xml @@ -1,7 +1,61 @@ + +Mapconverter is a format that is read by Mapopolis.com's +mapconverter application. + + +Mapconverter is an application used to create userland maps and map data for +Mapopolis.com's Mapopolis program. The mapconverter format is essentially +waypoint data prepared in a format that the mapconverter application will +accept. + + +The steps for using GPSBabel and Mapconverter go something like this: + + +Step 1: Create a mapconverter file using gpsbabel. + +gpsbabel -i geo -f geocaching.loc -o mapconverter -F foo.txt + +Step 2: Launch mapconverter.exe and choose foo.txt as your input file. + Click the begin button to have mapconverter process foo.txt. + + +If all goes successfully, you should have a file called "foo.pdb" ready +for syncing with your PDA. Put it wherever Mapopolis thinks it should be +on your PDA. + +
+Notes + + + +GPSBabel will write the name of its own output file in the output file + it creates as the input for Mapconverter. Mapconverter will replace + the extension of this filename with ".pdb". + + + + +The PocketPC version of Mapopolis doesn't notice files with the ".pdb" + extension. To make this work, change the extension to ".mlp" when + copying the mapconverter output to your PocketPC PDA. + + + + +Mapconverter only works with Mapopolis version 3.x. Mapopolis version + 4 will refuse to load mapconverter maps. There is no known work-around + for this at the time of this writing. + + + + +Mapconverter is no longer available from the Mapopolis website. If you + need a copy of mapconverter, ask on your local GPS Software discussion + forum and I'm sure someone will have it. As far as I know, It was never + actually acknowledged/supported by Mapopolis to begin with. + + + +
- - - Mapconverter is a format this is read by Mapopolis.com's -mapconverter application. Full details of it's usage are available in -the file README.mapconverter. - diff --git a/xmldoc/formats/options/igc-timeadj.xml b/xmldoc/formats/options/igc-timeadj.xml index 8b1378917..2d6def3c8 100644 --- a/xmldoc/formats/options/igc-timeadj.xml +++ b/xmldoc/formats/options/igc-timeadj.xml @@ -1 +1,16 @@ + +Sometimes there is a discrepancy between the internal clock in the barograph +instrument and GPS time which can result in the altitude and ground positions +not correlating correctly. This can be corrected manually by passing the time +difference in seconds between the two time domains through the "timeadj" +parameter. This can be any positive or negative integer: + +gpsbabel -i gpx -f baro.gpx -i igc -f my2D.igc -o igc,timeadj=27 -F my3D.igc + +GPSBabel can also attempt to deduce the time difference automatically. This +is done by comparing the time that it thinks that you landed on the GPS track +and the barograph and adjusting accordingly: + +gpsbabel -i gpx -f baro.gpx -i igc -f my2D.igc -o igc,timeadj=auto -F my3D.igc + diff --git a/xmldoc/formats/psp.xml b/xmldoc/formats/psp.xml index 90d1a7796..6c600418b 100644 --- a/xmldoc/formats/psp.xml +++ b/xmldoc/formats/psp.xml @@ -1,13 +1,12 @@ - - - - Microsoft's PocketStreets 2002 Pushpin (.PSP) format is -not yet completely documented. THE .PSP MODULE DOES NOT WORK WITH MS -STREETS & TRIPS 2002 .EST FILES. To create .PSP files from + +Microsoft's PocketStreets 2002 Pushpin (.PSP) format is +not yet completely documented. The .PSP module does not work with +MS Streets & Trips 2002 .EST files To create .PSP files from Streets & Trips 2002, you will need to have PocketStreets support installed. - - Please note that MS Streets & Trips only *EXPORTS* + + +Please note that MS Streets & Trips only exports .PSP files. It does not import them. MS Streets & Trips 2002 only imports CSV files. To use .PSP files, simply copy them over to the same folder on the mobile device as the map (.MPS), and open @@ -15,5 +14,210 @@ PocketStreets. It should also be noted that in the case a pushpin is outside of the exported map area, the pin will be "grayed-out" and unused in PocketStreets. This is a good thing as it allows us to create one big .PSP file that covers multiple .MPS files. -Unfortunately, you need one .PSP file for every .MPS file. :( - +Unfortunately, you need one .PSP file for every .MPS file. + +
+Frequently Asked Questions + + + + +Why should I use GPSBabel/psp to make pushpins when Streets & Trips (S&T) + already does that for me? + + + + +GPSBabel/psp has the advantage of being able to create pushpins +without + creating the associated map file and the need to "import" the waypoint + data into S&T. Through a series of scripts, you can create a dozen + or so PSP files in a few seconds as opposed to a few weeks using the + S&T interface. The maps are not going to change between sessions, + only the pins will. Why waste all that time creating maps when all you + really want are updated pins? As an aside, GPSBabel/psp creates points + with the proper coordinates + where S&T does not in some areas of the U.S. + (Nashville, TN for instance). + + + + + + +I keep getting a blank (32 byte) PSP file. + + + + +There are either no points to write, or you have botched the command + line for GPSBabel. GPSBabel is sensitive to UPPER and lower case + on the command line. A simple command line to create PSP files + looks like this: + +gpsbabel -i geo -f geocaching.loc -o psp -F NewOrleans.psp + + Note the use of "-f" for INPUT files and "-F" for OUTPUT files. + + + + + + +I've created a PSP file, now what do I do with it? + + + + +To use pushpins in Pocketstreets, you need to have both a map and a + pushpin file. These two files must exist in the same folder and have + exactly the same base name as the map. For example, the pins that + correspond to the map "NewOrleans.mps" should be named "NewOrleans.psp". + + + + + + +I don't have a map. What do I do now? + + + + +Create one using the "Export map to Pocketstreets" option in S&T. You + can also pick up some major city maps on the web from the MS Pocketstreets + website if you are interested in seeing how it works. + + + + + + +I have .EST files, not .PSP files. What's up with that? + + + + +In order to make PSP files, you need to use the "Export map to + Pocketstreets" function in S&T. .EST files are for use in S&T, not + Pocketstreets. + + + + + + + The .PSP files differ when I use GPSBabel/psp versus Pocketstreets to + create them. What's up? + + + + +Pocketstreets makes corrections to the S&T waypoint data upon initial + loading. GPSBabel/psp writes PSP files with these corrections already made. + Ask MS. + + + + + + +Does GPSBabel/psp work with (Autoroute, Mappoint, etc..) .PSP files? + + + + +As of this writing, I haven't seen any so I can't be sure. If they + follow the same layout as S&T 2002, I'd imagine so. + + + + + + + Does GPSBabel/psp work with (S&T 2001, S&T 2002, etc...) files? + + + + +MS changed the file layout between S&T 2001 and S&T 2002. The GPSBabel psp + module is known to work fine with S&T 2002 and 2003. + + + + + + +Does GPSBabel/psp work with (insert your country/location here) maps? + + + + +If it doesn't, feel free to inquire on the +GPSBabel-Misc +mailing list. + + + + + + +What do you mean S&T writes points with the wrong coordinates? + + + + +At some point in the "Export map to Pocketstreets" function in S&T, + it goofs the lat/long data. Points in Nashville tended to shift + 1.4 miles WEST of their original location. I'm not a geometry buff, + but I'd imagine they have a reference point for generating coordinates + that's wrong in (at least) that area. + + + + + + +I have 800 waypoints that cover a dozen or so Pocketstreets maps. + Do I need to to split my points up into smaller chunks to match the + area covered by the maps? + + + + + No. Pocketstreets will "ignore" points that are outside of the map + area. Points that are not on the current map will be "grayed out" + in pushpin explorer in Pocketsreets. This is the reason the PSP + module was written for GPSBabel in the first place. + + + + + + +Where can I find documentation for the layout of PSP files? + + + + +Just about everything I know about the PSP file format is documented + in the source. To the best of my knowledge, there is no documentation + (and for good reason, I've come to discover). + + + + + + +I have some other problem, what do I do? + + + + +Ask your question on the GPSBabel-Misc mailing list. + + + + +
+ diff --git a/xmldoc/formats/xmapwpt.xml b/xmldoc/formats/xmapwpt.xml index f4807b6a2..cbd2481e1 100644 --- a/xmldoc/formats/xmapwpt.xml +++ b/xmldoc/formats/xmapwpt.xml @@ -1,9 +1,77 @@ - - - - Delorme XMapHandHeld Street Atlas USA is another of the + +Delorme XMapHandHeld Street Atlas USA is another of the billion CSV variants. This is the format used by XmapHH SA USA on (at -least) PocketPC O/S. Please see README.xmapwpt for more information -on it's intricacies. This XMap is not to be confused with the XMap -mentioned above. Contributed to GPSBabel by Alex Mottram. +least) PocketPC O/S. + + +This XMap is not the same as the simpler +XMap format, which is used with Topo USA 4.0 +and XMapHH for Palm. + + +Delorme XMap Handheld .WPT for PocketPC is a bit of a kludge. This +chapter covers XMap Handheld Street Atlas USA edition. + + +XMap on the PocketPC stores its waypoints in individual .wpt files. +For example, waypoints generated by XMap on the PocketPC are stored +by default in the "My Documents" folder using the sequential names +"XMap1.wpt", "XMap2.wpt", ad nauseum. Needless to say, this is not very +efficient. + + +As writing multiple waypoint files is outside of the scope of GPSBabel, +GPSBabel chooses to write one big file, one waypoint per line. +Extracting lines from this file is left as an exercise for the end user. +A simple Perl script to handle this conversion is included at the end +of this chapter. + + +It should also be noted that reading multiple files +is indeed possible, but if you have more than a few points, it can be a task. +For example: + +gpsbabel -i xmapwpt -f Xmap1.wpt -f Xmap2.wpt -o mapsend -F mapsend.wpt + +will read the two Xmap .wpt files and write one mapsend file. This +is fine for a small handful of points, but could be quite cumbersome +for folks like me who have 100+ waypoints loaded into XMap. For *nix +folks, something as simple as: + +cat *.wpt > /tmp/foo.wpt +gpsbabel -i xmapwpt -f foo.wpt -o mapsend -F mapsend.wpt + +will do the trick just fine. + + +#!/full/path/to/perl +$INPUTFILE = @ARGV[0]; +$TARGETDIR = @ARGV[1]; +$FILENAME = @ARGV[2]; + +if (! $FILENAME) { + print "Usage: xmap_split.pl INPUT_FILE OUTPUT_DIRECTORY FILENAME_BASE\n"; + print " (i.e. xmapl_split.pl points.wpt /tmp/points GPSB)\n"; + print " (created GPSB0001-GPSBXXXX in /tmp/points/ from points.wpt)\n"; + exit; +} + +open (INFILE, $INPUTFILE) || die "Cannot open $INPUTFILE for read!\n"; + +while (<INFILE>) { + $lc++; + $filename = sprintf("%s/Gpsb%04d.wpt", $TARGETDIR, $lc); + + open (OUTFILE, ">$filename") || die "Cannot open $filename for write!\n"; + + print OUTFILE $_; + + close(OUTFILE); +} + +exit; + + + +Contributed to GPSBabel by Alex Mottram. diff --git a/xmldoc/makedoc b/xmldoc/makedoc index 2d458e389..48515fe8a 100755 --- a/xmldoc/makedoc +++ b/xmldoc/makedoc @@ -120,7 +120,6 @@ for (@formats) { $line[4] ($line[2]) END print FILE expandoptions($line[1]); - include($id,"formats"); $going = 1; $dooptions = 1; if ( defined($line[5]) && ($line[5] ne $line[2]) ) { @@ -134,6 +133,7 @@ END $dooptions=0; } } + include($id,"formats"); } elsif ($going && $dooptions && ($line[0] eq 'option')) { $nid = 'fmt_'.$id.'_o_'.$line[2]; -- 2.30.2